Add 'how to define spans' meta-guidance #3240
Open
+134
−1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
lmolkova
commented
Jan 3, 2026
kamphaus
reviewed
Jan 5, 2026
lmolkova
commented
Jan 5, 2026
lmolkova
commented
Jan 5, 2026
trask
reviewed
Jan 5, 2026
Comment on lines
212
to
213
| Don't try to capture all available properties as span attributes. Telemetry is | ||
| lossy, and it's important to assess the value-to-cost ratio of each referenced attribute. |
Member
There was a problem hiding this comment.
I didn't follow the tie in to being lossy
Member
Author
There was a problem hiding this comment.
moved this to attributes section and replaced with
Only include attributes that bring clear value - this allows keeping telemetry
volume and performance overhead low. Don't try to capture all available details.
When in doubt, don't reference additional attributes - they can be added incrementally
based on feedback.
| - When the span starts and ends. | ||
| - If this span represents a client call, specify whether it captures the logical call | ||
| (as observed by the API caller) or the physical call (per-try/per-attempt). | ||
| - Define a span per different operation type. |
Member
There was a problem hiding this comment.
I'm not sure what this is saying, maybe a short example could help?
Member
Author
There was a problem hiding this comment.
updated to
- Define a different span for different operations - e.g., when spans have different
kinds or a significantly different set of attributes.
For example, HTTP client and server spans are two independent definitions.
Messaging publishing and receiving are also different span types.
kamphaus
reviewed
Jan 5, 2026
lmolkova
force-pushed
the
how-to-define-spans
branch
from
0b17b67 to
a2914f1
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #1853